home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / Dev / Amiga-E / E_v3.2a_extras / PdSrc / rexxHostC / ReadMe next >
Text File  |  1995-01-01  |  10KB  |  248 lines
  1.  
  2. If you are an Amigoid to whom one or more of the following statements applies:
  3.  
  4.  
  5.     1. You always wanted to learn ARexx but the fact that it can't even flash
  6.     the screen by itself bothered you (well I know that there is \007),
  7.  
  8.     2. You badly need quick and easily created wrapper-programs for your new
  9.     great E routines using ARexx's monitoring capabilities,
  10.  
  11.     3. You want to write something really useful as PD, Shareware or
  12.     something, but don't know what people out there would need and truly
  13.     appreciate,
  14.  
  15.     4. You want to start programming in E in an unconventional way,
  16.  
  17.     5. You need some speial and quick functions for your ARexx scripts,
  18.  
  19.     6. You often listen to those PC/Macintosh los... sorry -- 'users' and
  20.     begin to envy them their 'servers' and stuff,
  21.  
  22.     7. You have your nose more or less in the middle of your face...
  23.  
  24.  
  25.     THIS IS FOR YOU !  IT WILL MAKE YOU HAPPY !
  26.  
  27.  
  28. What it is you're asking? Well this is a E module, called rexxHostC.m, two
  29. sources as example of using it, and this ReadMe.
  30.  
  31. The module provides you with an extremely user-friendly 'engin' for writing
  32. Rexx function-hosta (i.e. servers). Take a look on the 'mini_host.e' file to
  33. see how concise can an E program be! And it really provides ARexx with a
  34. Intuition function! The executable is 5112 bytes big.
  35.  
  36. The engin is object-oriented, it has been pretty thoroughly tested, and it
  37. returns all memory used. What else can I say...? Here comes the HOW-TO.
  38.  
  39. ---------------------------------------------------------------
  40.  
  41. After creating an instance of a rexxHostC object, by calling NEW rexxHostC()
  42. with required parameter/s, the program by itself will open rexsyslib.library,
  43. create a public port with the provided or default name, add it to ARexx's
  44. host list and [possibly after executing some user-provided function] enter a
  45. loop waiting for ARexx function-calls, intercepting them and executing. This
  46. loop will be broken if either:
  47.  
  48.     1. COMMAND 'bye' arrives at its port
  49.  
  50.     2. the program got ^C
  51.  
  52.     3. the method break() is executed [directly or not] by any callback
  53.  
  54. and then our instance of the rexxHostC object will do the cleanup, that is:
  55. reply the outstanding messages, delete the port, close the rexsyslib.library
  56. etc.  and commit suicide. In most cases the host will terminate [unless, for
  57. some strange reason, you decide otherwise and put lots of other code after
  58. it].
  59.  
  60. The rexxHostC class has quite a few methods, but you don't need most of them
  61. if you don't want them; they are only there to help you. Notice that the
  62. 'mini_host' demo uses no other method but the constructor!
  63.  
  64. Here comes short description of the available methods:
  65.  
  66. ---------------------------------------------------------------
  67.  
  68. CONSTRUCTOR:
  69.  
  70.     rexxHostC(  callback_list,
  71.                 name            = 'rexx_host',
  72.                 host_priority   = -50,
  73.                 func_ptr        = NIL )
  74.  
  75. where:
  76.  
  77.     callback_list
  78.     -------------
  79.  
  80.     is a list of pairs: [ S, C, S, C, ... , S, C ]
  81.  
  82.     'S' being an UPPERCASE string like 'BEEP' or 'BYE_BYE' [quotes
  83.     included!], representing the name of the function you are adding to ARexx
  84.     'C' is a callback i.e. a pointer to a PROC'ess; it can also be a quoted
  85.     expression, a string like 'I love this\n', or just NIL; in the last
  86.     case ARexx will not find any function with this callback's name --
  87.     just as if  the name-string was not there. This callback-list is
  88.     [roughly] checked for validity and if it doesn't conform exception 4
  89.     i.e. ERR_BADLIST will be raised.
  90.  
  91.     Callbacks take no arguments [not directly anyway] and return either
  92.     nothing or [nicer thing to do] a string [not necessarily an EString]
  93.     like 'this is your callback speaking', 'TRUE', or '666'. ARexx will by
  94.     himself [!] translate those strings that represent numbers [like the last
  95.     one here] to numbers. It is as easy as that for direct values, for
  96.     variables you will probably use the supplied routines longToStr() and
  97.     charToStr(), which turn an integer like 69 or a char like "A" into a
  98.     string for ARexx.  See the 'big_host' demo-source for that. As to
  99.     callbacks' arguments there are three support routines supplied for that
  100.     purpose: getNumArgs(), getStr( index ) and getNum( index ), read later on
  101.     about them.
  102.  
  103.     name
  104.     ----
  105.  
  106.     [optional] is a string representing name for your message-port which must
  107.     be different from all currently present public ports present in the
  108.     system or you will get exception 2 i.e. 'ERR_NOTUNIQUE'.
  109.  
  110.  
  111.     host_priority
  112.     --------------
  113.  
  114.     [optional] is the priority AMONG all Arexx libraries and hosts. It is NOT
  115.     any task priority, so don't be too surprised at the low default value. In
  116.     fact you SHOULD NEVER USE HIGHER priority than any of the libraries/hosts
  117.     you will be calling, DEADLOCK will result otherwise! I would personally
  118.     never attempt anything over 0. 'host_priority' value will be clipped to
  119.     a number between -100 and 100.
  120.  
  121.  
  122.     func_ptr
  123.     --------
  124.  
  125.     is the [optional] pointer to function you want executed AFTER setup is
  126.     completed, probably nothing more important than announcing that it is
  127.     waiting for Rexx messages.
  128.  
  129.  
  130. Note that 'callback_list' is the only argument you must give the constructor.
  131. Another unusual thing is that we have no public destructor.
  132.  
  133. ---------------------------------------------------------------
  134.  
  135.     num := getNumArgs()
  136.            ------------
  137.  
  138.     returns the number of arguments the function in question got from ARexx,
  139.     it will be something between 0 and 15.
  140.  
  141. ---------------------------------------------------------------
  142.  
  143.     string, fGood := getStr( index )
  144.                      ---------------
  145.  
  146.     gives you the argument number 'index' as a string, the second BOOLEAN
  147.     return-value tells you whether this argument is valid, that is -- if it
  148.     really came from ARexx [this you might already know if you have
  149.     previously called getNumArgs()].
  150.  
  151.     N.B. It starts from 1, as the argument #0 is the command itself!
  152.  
  153. ---------------------------------------------------------------
  154.  
  155.     num, fGood := getNum( index )
  156.                   ---------------
  157.  
  158.     gives you the argument number 'index' as an integer, the second BOOLEAN
  159.     return-value tells you whether this argument is valid, that is -- if the
  160.     argument-string with this index string really came from ARexx and if it
  161.     is a number.
  162.  
  163.     N.B. It starts from 1, as the argument #0 is the command itself!
  164.  
  165. ---------------------------------------------------------------
  166.  
  167.     break()
  168.     -------
  169.  
  170.     breaks the waiting/receiving/executing loop and kills the rexxHandlerC
  171.     object.
  172.  
  173. ---------------------------------------------------------------
  174.  
  175.     str := longToStr( long )
  176.            -----------------
  177.  
  178.     str := charToStr( char )
  179.            -----------------
  180.  
  181.     as already said, these functions will turn an integer or a char
  182.     respectively into a string just as ARexx wants it for a return-value from
  183.     its function, it is only needed for variables, the direct values can be
  184.     returned with strings like '123' or 'oui monsieur'.
  185.  
  186. ---------------------------------------------------------------
  187.  
  188.     major, minor := version()
  189.                     ---------
  190.  
  191.     returns major and minor version number of the rexxHostC.m
  192.     the current values are bye the way: 0 and 4
  193.  
  194. =======================================================================
  195.  
  196. EXCEPTIONS that might be raised by rexxHostC-object:
  197.  
  198.  
  199. "MEM"                   meaning: 'not enough memory'
  200.  
  201. "REXX"                  meaning: 'rexxsyslib.library not found'
  202.  
  203. ERR_NONAME      = 1     meaning: 'I got NIL as port-name'
  204.  
  205. ERR_NOTUNIQUE   = 2     meaning: 'port-name not unique'
  206.  
  207. ERR_LISTNIL     = 3     meaning: 'callback-list ptr NIL'
  208.  
  209. ERR_BADLIST     = 4     meaning: 'bad callback-list'
  210.  
  211. ERR_NOTADDED    = 5     meaning: 'host not added to ARexx list...'
  212.  
  213. ---------------------------------------------------------------
  214.  
  215. LIMITATIONS:
  216.  
  217. There are two major I can think of:
  218.  
  219.     1. As all other similar Rexx hosts I met [for example RexxFuncHost by
  220.     Donald T. Meyer] one such active host screens all other from receiving
  221.     function-calls; so that ONLY ONE CAN BE EFFECTIVE AT ANY TIME.  This is
  222.     due to the fact that, differently than with libraries, ARexx will not
  223.     send your function-call to any other host whatever error was reported by
  224.     the one that received it. It would be possible to find a solution to that
  225.     -- if I still feel any urge to play with this piece of software I might
  226.     do that -- but in practice it shouldn't be so much of a problem
  227.     considering E's lightning speed of compilation. If you already have the
  228.     callbacks, you can create a new host in couple of minutes and launch it
  229.     in place of the previously running one. It might even be possible to have
  230.     dynamically created callback-lists: if/when we start to get flooded with
  231.     great PD/ShareWare/commercial modules containing just callback-lists and
  232.     callbacks themselves [there would be some problems with getting the
  233.     arguments for the callbacks though], you would be able to manage them
  234.     dynamically from ARexx to be included in just one rexxHostC-based server.
  235.  
  236.     2. UPPER/lower case does not matter for all function-calls. It wouldn't
  237.     be any problem to implement this as optional, but I doubt whether it
  238.     would be so useful. Both ARexx and AmigaDOS tend to be case-insensitive
  239.     in most cases, and preventing ARexx from turning the name in your
  240.     function-call to uppercase requires additional work.
  241.  
  242.  
  243. This was written in E v3.0b and v3.1a [registered version], by Piotr Obminski
  244. in December 1994. It is, an off-spin of a much larger project, but I
  245. found it so cute that I decided to polish it and present it to the so called
  246. 'Amiga community' [as community service]. The example-proggies are PD, but
  247. the rexxHostC.m is Copyrighted FreeWare by me that is Piotr Obminski.
  248.